home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 October: Mac OS SDK / Dev.CD Oct 00 SDK1.toast / Development Kits / Mac OS / Multiprocessing 2.1v2 SDK / Sample Code / MPFileCopy1.0b1 / MoreIsBetterParts / TradDriverLoaderLib / TradDriverLoaderLib.h < prev   
Encoding:
C/C++ Source or Header  |  1999-02-25  |  10.4 KB  |  227 lines  |  [TEXT/CWIE]
  1. /*
  2.     File:        TradDriverLoaderLib.h
  3.  
  4.     Contains:    C interface for the pseudo-DriverLoaderLib for 'DRVR's.
  5.  
  6.     Written by:    Quinn
  7.  
  8.     Copyright:    Copyright © 1996-1999 by Apple Computer, Inc., all rights reserved.
  9.  
  10.                 You may incorporate this Apple sample source code into your program(s) without
  11.                 restriction. This Apple sample source code has been provided "AS IS" and the
  12.                 responsibility for its operation is yours. You are not permitted to redistribute
  13.                 this Apple sample source code as "Apple sample source code" after having made
  14.                 changes. If you're going to re-distribute the source, we require that you make
  15.                 it clear in the source that the code was descended from Apple sample source
  16.                 code, but that you've made changes.
  17.  
  18.     Change History (most recent first):
  19.  
  20.          <1>     25/2/99    Quinn   First checked in.
  21. */
  22.  
  23. #pragma once
  24.  
  25. /////////////////////////////////////////////////////////////////
  26. // MoreIsBetter Setup
  27.  
  28. #include "MoreSetup.h"
  29.  
  30. /////////////////////////////////////////////////////////////////
  31. // Mac OS Interfaces
  32.  
  33. #include <MacTypes.h>
  34. #include <Devices.h>
  35.  
  36. #ifdef __cplusplus
  37. extern "C" {
  38. #endif
  39.  
  40. ///////////////////////////////////////////////////////////////////////////
  41.  
  42. // The following routines are implemented with semantics virtually identical
  43. //  to those found in DriverLoaderLib.  You should look in
  44. //  "Designing PCI Cards and Drivers for Power Macintosh Computers" for
  45. //  documentation.  You can FTP an electronic copy from:
  46. //  <http://developer.apple.com/macos/opentransport/docs/dev/Designing_PCI_Cards_Drivers.pdf>
  47.  
  48. extern pascal SInt16 TradHigherDriverVersion(NumVersion *dv1, NumVersion *dv2);
  49.  
  50. extern pascal UnitNumber TradHighestUnitNumber(void);
  51.  
  52. extern pascal OSErr TradDriverGestaltOn(DriverRefNum refNum);
  53.  
  54. extern pascal OSErr TradDriverGestaltOff(DriverRefNum refNum);
  55.  
  56. extern pascal Boolean TradDriverGestaltIsOn(DriverFlags flags);
  57.  
  58. extern pascal OSErr TradLookupDrivers(UnitNumber beginningUnit,
  59.                                         UnitNumber endingUnit,
  60.                                         Boolean emptyUnits,
  61.                                         ItemCount *returnedRefNums, 
  62.                                         DriverRefNum *refNums);
  63.  
  64. ///////////////////////////////////////////////////////////////////////////
  65.  
  66. // The following routines are similar to the corresponding routines in
  67. //  DriverLoaderLib, but their interface differs because of the
  68. //  inherent differences between 'DRVR's and 'ndrv's.  The comments
  69. //  cover the differences for each routine.  If there's a difference
  70. //  that's not commented, it's most probably a bug and you should let
  71. //  me know.
  72.  
  73. extern pascal OSErr TradInstallDriverFromPtr(DRVRHeaderPtr driver,
  74.                                                 UnitNumber beginningUnit,
  75.                                                 UnitNumber endingUnit,
  76.                                                 DriverRefNum *refNum);
  77.     // This routine is similar to InstallDriverFromMemory except
  78.     //  that you pass a pointer to the 'DRVR', rather than a base pointer
  79.     //  and length.  This pointer is copied verbatim into the dCtlDriver
  80.     //  field of the DCE, so you have to make sure that it's in
  81.     //  the system heap if the driver is going to hang around longer than
  82.     //  your application.
  83.     // One other deviation from InstallDriverFromMemory is that this
  84.     //  call won't replace an existing driver.  This is because 'DRVR's
  85.     //  don't have infrastructure to support this.  If there's already
  86.     //  a driver of the same name in the unit table, the call will fail
  87.     //  with a dupFNErr, and *refNum will be set to the refnum of the
  88.     //  existing driver.
  89.     // The semantics of the endingUnit match those of DriverLoaderLib,
  90.     //  ie the call will not grow the unit table unless endingUnit is
  91.     //  greater than TradHighestUnitNumber.  The simplest way to work
  92.     //  this is to pass TradHighestUnitNumber() + 1 to endingUnit.
  93.     // If the call fails, it's your responsibility to dispose of the
  94.     //  the driver pointer.  If it succeeds, the system has a copy
  95.     //  of the pointer, which can be disposed by calling TradRemoveDriver.
  96.  
  97. extern pascal OSErr TradInstallDriverFromHandle(DRVRHeaderHandle driver,
  98.                                                 UnitNumber beginningUnit,
  99.                                                 UnitNumber endingUnit,
  100.                                                 DriverRefNum *refNum);
  101.     // This routine is similar to InstallDriverFromMemory except
  102.     //  that you pass a handle to the 'DRVR', rather than a base pointer
  103.     //  and length.  This is generally more convenient in the traditional
  104.     //  'DRVR' world.
  105.     // In most other respects, this routine works like TradInstallDriverFromPtr.
  106.     //  The routine simply creates a pointer in the system heap and copies
  107.     //  your driver into it, then calls TradInstallDriverFromPtr.  Because
  108.     //  a copy is made, you do not have to ensure that the handle you
  109.     //  pass in is in the system heap.
  110.     // Regardless of whether call succeeds or fails, it's your responsibility
  111.     //  to dispose of the driver handle.
  112.     
  113. extern pascal OSErr TradInstallDriverFromResource(SInt16 rsrcID, StringPtr rsrcName,
  114.                                                 UnitNumber beginningUnit,
  115.                                                 UnitNumber endingUnit,
  116.                                                 DriverRefNum *refNum);
  117.     // This call offers functionality like InstallDriverFromFile.
  118.     //  It differs from InstallDriverFromFile in that the driver is expected
  119.     //  to be in a resource in the current resource file.  If rsrcName is nil,
  120.     //  the call uses Get1Resource('DRVR', rsrcID) to get the driver.  If
  121.     //  rsrcName is not nil, it uses Get1NamedResource('DRVR', rsrcName)
  122.     //  to get the driver.
  123.     // In most other respects, this routine works like TradInstallDriverFromPtr.
  124.     // If the call fails, the routine will clean up after itself.  If the
  125.     //  call succeeds, the driver code is left as a memory block in the system
  126.     //  heap, which can be cleaned up by calling TradRemoveDriver.
  127.  
  128. extern pascal OSErr TradGetDriverInformation(DriverRefNum refNum,
  129.                                                 UnitNumber *thisUnit,
  130.                                                 DriverFlags *flags,
  131.                                                 StringPtr name,
  132.                                                 DRVRHeaderPtr *driverHeader
  133.                                                 );
  134.     // This routine is like GetDriverInformation except that it only
  135.     //  returns information that's pertinant to the traditional 'DRVR'
  136.     //  world.  driverHeader comes back as a pointer to the beginning
  137.     //  of the 'DRVR' header.
  138.     // Note that this routine works for both drivers installed by
  139.     //  this library and other drivers, however for drivers not installed
  140.     //  by this library (ie 'RAM'-based drivers), driverHeader may be a 
  141.     //  half dereferenced handle, locked or unlocked.  You have been warned.
  142.     // Also, driverHeader can come back set to nil, if the driver
  143.     //  is installed but its code has been purged, for example a DA.
  144.     //  You must check for this before deferencing it.  If driverHeader
  145.     //  is set to nil, name will be set to the empty string.
  146.  
  147. extern pascal OSErr TradOpenInstalledDriver(DriverRefNum refNum, SInt8 ioPermission);
  148.     // This routine has the same semantics as OpenInstalledDriver
  149.     //  except that the ioPermission parameter must be fsRdWrPerm.  This is
  150.     //  because we call through to the Device Manager's OpenDriver routine,
  151.     //  and that doesn't support passing in permissions.  I could switch the
  152.     //  implementation to use PBOpen, but PBOpen is a trap fraught with much
  153.     //  danger, so I'm avoiding it at the moment.
  154.     // The danger associated with PBOpen is that it's highly overloaded,
  155.     //  being used for FSOpen, PBOpen, PBHOpen, OpenSlot, OpenDriver,
  156.     //  OpenDeskAcc, and so on.  If you get the glue wrong, you die in
  157.     //  strange and evil ways.  So I'm bypassing the entire problem by
  158.     //  ignoring ioPermission.  I may revisit this decision, but not soon.
  159.  
  160. extern pascal OSErr TradRemoveDriver(DriverRefNum refNum, Boolean immediate);
  161.     // This routine implements similar semantics to RemoveDriver, except
  162.     //  that the Immediate parameter must be false.  This is because
  163.     //  we close the driver using PBCloseSync, which is a queued
  164.     //  command, just like all the others.  We have no way to bypass
  165.     //  this.
  166.     // An important thing to note is that you should only call this on drivers
  167.     //  you installed using this library's TradInstallDriverFromHandle
  168.     //  and TradInstallDriverFromResource routine.  Don't call it on
  169.     //  drivers installed by other people and be careful when calling it on
  170.     //  drivers installed using TradInstallDriverFromPtr because you might
  171.     //  be disposing the driver code even though a) it might not actually be a
  172.     //  Memory Manager pointer block, or b) it might be still in use
  173.     //  by another driver.
  174.  
  175. extern pascal OSErr TradRenameDriver(DriverRefNum refNum, ConstStr255Param newDriverName);
  176.     // This routine is implemented with the caveat that you can't
  177.     //  make the driver name longer.  This is because the 'DRVR'
  178.     //  name is actually stored in the code resource which implements
  179.     //  the driver, and making it longer would cause it to run into
  180.     //  the code that immediately follows the name.
  181.     // The reason why I implemented this routine at all is because
  182.     //  it's useful for installing multiple copies of the same driver.
  183.     //  For example, you can install ".Q_Out", then rename it to
  184.     //  ".QAOut", and then install ".Q_Out" again, and rename that to
  185.     //  ".QBOut".  This can be very useful when testing and debugging
  186.     //  your driver (or TradDriverLoaderLib for that matter :).
  187.     // You should take extreme care when calling this routine on drivers that
  188.     //  weren't installed with this library.  Some of these drivers might
  189.     //  not like being renamed in this way.
  190.  
  191. ///////////////////////////////////////////////////////////////////////////
  192.  
  193. // The following routines from DriverLoaderLib were not implemented because
  194. //  they make no sense at all in the world of 'DRVR's.
  195.  
  196. // VerifyFragmentAsDriver
  197. // GetDriverMemoryFragment
  198. // GetDriverDiskFragment
  199. // InstallDriverFromFragment
  200. // SetDriverClosureMemory
  201. // -- If they've got fragment in the name, it's hard to map them into the
  202. // 'DRVR' world.  Traditional 'DRVR's just aren't code fragments!
  203.  
  204. // InstallDriverFromFile -- This routine assumes that there's only
  205. //    one driver in a file, which is not the case for traditional 'DRVR's
  206. //  which are normally stored as resources.  The basic functionality has
  207. //  been subsumed by TradInstallDriverFromResource.
  208.  
  209. // InstallDriverFromDisk
  210. // FindDriversForDevice
  211. // FindDriverCandidates
  212. // ScanDriverCandidates
  213. // GetDriverForDevice
  214. // InstallDriverForDevice
  215. // -- These routines all assume that there's some magic way of matching
  216. //  drivers to their name register nodes.  In the traditional world, there
  217. //  is no name registry and, even if there was, there's no way to match
  218. //  devices against hardware.  So these routines are not sensible in the
  219. //  traditional world. 
  220.  
  221. // ReplaceDriverWithFragment -- There's no good way to replace a traditional
  222. //  device driver; the infrastructure just isn't there.
  223.  
  224. #ifdef __cplusplus
  225. }
  226. #endif
  227.